Skip to content

Add vg unitigs: cover the haplotype k-mers of a graph with walks - #5109

Open
glennhickey wants to merge 1 commit into
masterfrom
vg-unitigs
Open

glennhickey wants to merge 1 commit into
masterfrom
vg-unitigs

Conversation

@glennhickey

Copy link
Copy Markdown
Contributor

A linear k-mer tool cannot read a graph, and running it on every haplotype reads the shared sequence once per haplotype. vg unitigs writes graph walks whose sequences spell every k-mer the haplotypes spell, each once, so scanning the output sees what scanning all the haplotypes would.

A k-mer here is a haplotype-consistent walk spelling k bases, so the same sequence in two places is two k-mers. A unitig is a maximal chain of k-mers in which each has one successor, that successor has one predecessor, and no haplotype begins or ends in between. Every k-mer lies in exactly one unitig, and a unitig is a substring of every haplotype holding any of its k-mers, so its support is one number.

With --gref the k-mers along a single gref path are left out, since the gref sequence already spells them, and what remains are the junction tigs. The gref paths and the tigs together are a cover: FASTA a linear tool can scan in place of the haplotypes, with --gaf giving each tig's walk for mapping results back.

Two supporting pieces come with it:

  • WalkInterval (walk_interval.hpp) is a walk with offsets into its first and last node, which is what a tig is. It spells its sequence, extends and cuts.
  • GrefIndex (gref.hpp) indexes a gref's paths so a walk can be placed on them: which gref contig a visit lies on, at what coordinate and orientation, and whether that contig is the reference or an alt.

GrefIndex::find_path() keyed its bracketed names, NAME[START] and NAME[START-END], off a start above 0, so it could not find a path whose subrange began at 0. A GBWT keeps a subrange's start in the count field of the path name and reads it back only when it is nonzero, so such a path arrives indistinguishable from one covering a whole contig, while a tool that read it still writes NAME[0-END] for what it found. The bracketed names now go in for every path.

Some of the API lands here but is called by vg lift in the PR stacked on this one, not by anything here: GrefCover::read_top_level_snarls(), GrefIndex::interval(), find_path(), GrefPlacement::along_one_path, the before/after arguments of GrefIndex::place(), and parse_gaf_columns()/parse_walk().

Tested on macOS: make -j8 clean, scripts/lint.py clean, and prove t/58_vg_unitigs.t t/11_vg_paths.t green (155 assertions). 58_vg_unitigs.t pins unitig counts and lengths for a triallelic SNP, k-mer set equality and disjointness against the paths with and without a gref, support values, placement strings for an insertion, a SNP, a deletion and an inversion, thread-count invariance, and the unsupported-gref warning.

🤖 Generated with Claude Code

A linear k-mer tool cannot read a graph, and running it on every haplotype
reads the shared sequence once per haplotype. vg unitigs writes a set of graph
walks whose sequences spell every k-mer the haplotypes spell, each exactly
once, so a scan of the output sees what a scan of all the haplotypes would.

A k-mer here is a haplotype-consistent walk spelling k bases, so the same
sequence in two places is two k-mers. A unitig is a maximal chain of k-mers in
which each has one successor, that successor has one predecessor, and no
haplotype begins or ends in between. Every k-mer lies in exactly one unitig,
and a unitig is a substring of every haplotype holding any of its k-mers, so
its support is one number.

With --gref the k-mers that lie along a single gref path are left out, since
the gref sequence already spells them, and what remains are the junction tigs.
The gref paths and the tigs together are a cover: FASTA a linear tool can scan
in place of the haplotypes, with --gaf giving each tig's walk for mapping the
results back.

Two supporting pieces come with it. WalkInterval (walk_interval.hpp) is a walk
with offsets into its first and last node, which is what a tig is, and it can
spell its sequence, extend, and cut. GrefIndex (gref.hpp) indexes a gref's
paths so a walk can be placed on them: it answers which gref contig a visit
lies on, at what coordinate and orientation, and whether that contig is the
reference or an alt. A tig carries that placement, which is how the cover
reports where it came from.

GrefIndex::find_path() keyed its bracketed names, NAME[START] and
NAME[START-END], off a start above 0, so it could not find a path whose
subrange began at 0. A GBWT keeps a subrange's start in the count field of the
path name and reads it back only when it is nonzero, so such a path arrives
indistinguishable from one covering a whole contig, while a tool that read it
still writes NAME[0-END] for what it found. The bracketed names now go in for
every path.

Some of the API this adds is used by vg lift in the PR that follows, not here:
GrefCover::read_top_level_snarls(), GrefIndex::interval(), find_path() and
GrefPlacement::along_one_path, the before/after arguments of GrefIndex::place(),
and parse_gaf_columns()/parse_walk() in walk_interval.hpp.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants